home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / DevCon / Washington_1988 / DevCon88.3 / IEEE / src / spp.doc
Encoding:
Text File  |  1992-08-27  |  7.2 KB  |  249 lines
  1.  
  2. Documentation for spp   (assembly language preprocessor)
  3.     written by Dale Luck
  4.  
  5. This preprocessor was written for the Motorola family 68k family.
  6.  
  7. It adds 7 structured instructions to the assembler.
  8.  
  9. These instructions are if/else/endif
  10.                        repeat/until
  11.                        while/whend
  12.  
  13. The use of these constructs makes assembly code much more readable
  14. and maintainable as well as makes it easier to write in the first
  15. place.
  16.  
  17. I wrote this preprocessor about 7 years ago when the 68000 first
  18. came out and I found out the the cmp/bxx pair did not work the
  19. way I thought was intuitive. For example
  20. If I want #1 to be moved into d7 if d1>d0 then
  21.  
  22. I wrote
  23.     cmp    d1,d0
  24.     ble    foo
  25.         moveq    #1,d7
  26. foo:
  27.  
  28.     I expected the 68k to take the branch if d1 was le to d0.
  29.     But NNOOOOOOOO!
  30.     It takes the branch if d0 is le to d1.
  31.  
  32.     Instead, I now write:
  33.  
  34.     if d1>d0
  35.         moveq    #1,d7
  36.     endif
  37.  
  38. This has a couple advantages:
  39.     I now see that d7 is loaded with #1 if d1>d0 as well as I did
  40.     not have to think up another stupid label that I will never
  41.     use again. Also note that I can now line my indentations up
  42.     so that I can match my endifs up if withs and make sure I've
  43.     closed all my flow control logic.
  44.  
  45. I supposed your wondering what spp generates:
  46.     In the last case, it will generate:
  47.     cmp    d1,d0
  48.     bgt.s    if000001    ; or some such label
  49.         moveq    #1,d7
  50. if000001:
  51.  
  52.     It automatically makes forward branches short. Which is what
  53.     I need in 80% of all my code. When the branch is too long,
  54.     the assembler complains, and then I fix it with a modifier.
  55.  
  56. Modifiers are little key characters that begin with a '.'.
  57.  
  58.     For instance to make the example a long branch I use .ex
  59.     if d1>d0 .ex
  60.     If I wanted to make the comparison a long comparison I use
  61.     if d1>d0.l
  62.     I can have more than one modifier on the line so
  63.  
  64.     if d1>d0.b    .ex
  65.         a whole bunch of assembly code
  66.     else    .ex
  67.         a whole more bunch of code
  68.     endif
  69.  
  70. For whend and until, it never generates a short branch since the
  71. branch is backward. The assembler should be able to figure out
  72. if it can use a short branch.
  73.  
  74. Spp looks for special cases. For example,
  75.     if d1>#0.l
  76. will generate
  77.     tst.l    d1
  78.     ble    ifxxxxxx
  79. However thanks to the 68k's well thought out instructions, you have
  80. to use
  81.     if #0<a0.l
  82. the it will generate
  83.     cmp.l    #0,a0
  84. It looks for the second variable being #0 to use the tst instructions.
  85.  
  86. You can also treat variables like booleans.
  87.     if d0
  88. Will generate
  89.     tst    d0
  90.     beq    if00000
  91. Assuming you want to execute the body of the if statement if d0 is nonzero.
  92.  
  93. If you are clever enough to have the condition codes of the 68k already
  94. setup so that you do not need the tst or compare. for example
  95.  
  96.     move.l    d0,d1    ; sets condition codes
  97.     if >
  98.     endif
  99. Will insert a ble in there, figuring you want to execute the body if
  100.     d1 is greater than zero
  101. If you need to get real down and dirty you can use some more special
  102. modifiers.
  103.     add.l    d0,d0    ; will shift d0 left by one
  104.     if .cs
  105.     endif
  106. Will do the body if the carry flag was set.
  107. In general all the .ge .le .lt, .cc etc are legal here
  108. You are not limited to using registers and immediate values for your
  109. relation. However it must be able to replaced by a simple compare
  110. instruction. so
  111. if sign is a memory location, you can use
  112.     if sign>#0
  113. to generate
  114.     tst.l    sign
  115.     ble    ifxxxxxx
  116. If MinX is an offset into some kind of structure you can use
  117.     if MinX(a0)>d0.l
  118. to generate
  119.     cmp.l    MinX(a0),d0
  120.     ble    ifxxxxxx
  121.  
  122. The keywords if,until,while require a relational expression.
  123. The other keywords are just branch targets.
  124.  
  125. The relational expression can take many forms. The relational
  126. expression must be able to be reduced to a single cmp or tst
  127. instruction. I've found that this takes care of 90% of all
  128. cases where I need to control the flow of my program. For those
  129. more complex cases, it is not difficult to break it down into
  130. a couple instructions.
  131.  
  132. legal modifiers
  133.     .ex        make branch into long branch (suppress .s)
  134.     .l        make comparison a long
  135.     .b        make comparison a byte
  136.     .w        make comparison a word
  137.     .u        make comparison unsigned
  138.  
  139. legal modifiers/relations
  140.     .cs        carry set
  141.     .cc        carry clear
  142.     .mi        minus
  143.     .pl        plus
  144.     .vc        overflow clear
  145.     .vs        overflow set
  146.  
  147. legal    relation operators
  148.     =        equal
  149.     <>        not equal
  150.     >        greater than
  151.     <        less than
  152.     >=        greater than or equal
  153.     <=        less than or equal
  154.     
  155.  
  156. The keywords are searched for wherever a standard 68k mnemonic
  157. is expected. These examples are meant to be examples of the
  158. use of the preprocessor, so there may be logic flaws in code itself.
  159.  
  160. some example code:
  161. strcat:
  162. *    inputs a0,a1 ptr to strings
  163. *    cat a1 onto a0
  164. *    search for end of a0
  165.     repeat
  166.     until    (a0)+=#0.b    ; end of string a0?
  167. *    back a0 up by one
  168.     subq.l    #1,a0
  169.  
  170. *    now tack a1 onto end of a0
  171.     repeat
  172.         move.b    (a1)+,(a0)+
  173.     until =            ; end of string a1?
  174.     rts
  175.  
  176. * is <d0,d1> inside a rectangle defined by minx,miny,maxx,maxy.
  177. * the box dimensions are from a structure pointed to by a0
  178. *    returns d0 = 0 if <d0,d1> outside of box
  179. *    returns d0 = 1 if <d0,d1> inside of box
  180. inside:
  181.     if d0>=minx(a0)
  182.         if d0<=maxx(a0)
  183.             if d1>=miny(a0)
  184.                 if d1<=maxy(a0)
  185.                     moveq    #1,d0    ; return true
  186.                     rts
  187.                 endif
  188.             endif
  189.         endif
  190.     endif
  191.     moveq    #0,d0    ; return false
  192.     rts
  193.  
  194. spp does not handle unmatched control structures very well. So when
  195. I write code I almost always match them up first and fill the body
  196. in later.
  197.  
  198. ********************************************************************
  199. *                           COMERCIAL TIME                         *
  200. ********************************************************************
  201.  
  202. Redistribution of this code.
  203. This version of the binary is free for anyone that wants to use it.
  204. You must distribute a complete copy of this file along with the binary.
  205. Both so people can understand how to use it as well as they will
  206. know where to go if they want an update. It is ok for the binary and this
  207. file to be released onto pd disks.
  208.  
  209. My name/address:
  210.         Dale Luck
  211.         1881 Ellwell Drive
  212.         Milpitas, Ca. 95035
  213.         work phone 408-262-1469
  214.         email pyramid!oliveb!amiga!dale
  215.  
  216. I provide no telephone support accept to those that have the source.
  217. I'm hoping that this file is good enough documentation. If I'm wrong
  218. I'm happy to make additions/changes to improve it.
  219.  
  220. The source is available for a fee of 25$
  221. It compiles under aztec small everything model. I have not tried
  222. compiling under lattice but I suspect there should not be a problem.
  223.  
  224. I plan on adding more error checking so that it does not blow up
  225. when it gets unmatched control statements. Also I want to add
  226. a for/next construct that will use the dbxx facility of the
  227. 68k. Plus any other changes made from prompts of users besides
  228. myself.
  229.  
  230. So if there is a second version.
  231. The binary will become 'shareware.' Donations of 15$ will be appreciated.
  232.  
  233. For those that have purchased the source of the original version,
  234. I will update their source free. I will be keeping a list of everyone
  235. that is entitled to the updates.
  236.  
  237. If there are more updates after that I will probably need to get
  238. some more money to pay for disks, mailing, etc. Maybe another 5-10$
  239.  
  240. For those that did not get the original source. The new source will
  241. cost 30$
  242.  
  243. If you want to include this program with your other programs that you
  244. sell you should call me.
  245.  
  246. ********************************************************************
  247. *                        end of commercial                         *
  248. ********************************************************************
  249.